Skip to main content
POST

​
Overview

The CSV upload endpoint lets you bootstrap a campaign directly from a spreadsheet. Nexus validates the file, creates a batch, normalises the columns based on the agent’s variable schema, and inserts the calls in a single transaction.

​
Prerequisites

  • Bearer token for the workspace admin who owns the contacts.
  • CSV file containing the columns required by the agent.
  • At least one provisioned phone number to associate with the batch.

​
Request

​
string
required
Bearer token for the workspace admin.
CSV/Excel File Requirements:
  • Supported formats: CSV (.csv) or Excel (.xls, .xlsx)
  • Must include a header row
  • Must include phoneNumber column (required)
  • Must include all mandatory variables defined by the agent
  • CSV headers should match agent variable keys (e.g., phoneNumber, name, account_id, custom_field_1)
  • The phoneNumber column is required; all other columns are flexible based on your agent’s needs
  • Extra columns are stored and forwarded to the agent state machine
  • File encoding should be UTF-8
  • Empty files or files with no valid rows will be rejected
File Processing:
  • The system automatically detects file type by extension
  • Excel files use the first sheet
  • Invalid rows are identified and reported (unless type="true")
  • Data is normalized and validated against agent requirements
  • Phone numbers are deduplicated (only the first occurrence is kept)

​
Response

​
object
required
Summary of the created batch, including totals and calling numbers.

​
Error Handling

  • 400 Bad Request – Missing file, empty CSV, invalid batchType, invalid User ID format, missing required fields, or unsupported file type.
  • 404 Not Found – User not found, organization not found, no agent found for calling numbers, or no language configured for agent.
  • 422 Unprocessable Entity – CSV contains invalid rows (when type="false"). Response includes details of invalid rows.
  • 500 Internal Server Error – File parsing failed, database error, or other server errors.
Follow up with GET /api/call/batch-details/{batchId} to confirm the imported rows match the expected total.

Authorizations

​
Authorization
string
header
required

Bearer token authentication for workspace access

Body

multipart/form-data
​
file
file
required
​
userId
string
required
Example:

"64e5f12345abcdef12345678"

​
batchName
string
required
Example:

"Marketing Campaign May 2025"

​
callingNumbers
string
required
Example:

"[\"64e5f12345abcdef87654321\"]"

​
batchType
enum<string>
required
Available options:
outbound,
mixed
Example:

"outbound"

​
enableDNC
string
Example:

"true"

​
type
string
Example:

"false"

​
retry
number
Example:

3

​
delay
number
Example:

60

​
timezone
string
Example:

"America/New_York"

​
callingHour
string
Example:

"{\"start\":\"09:00\",\"end\":\"17:00\"}"

​
allowedDays
string
Example:

"[1,2,3,4,5]"

Response

CSV uploaded successfully